home *** CD-ROM | disk | FTP | other *** search
/ MACD 5 / MACD 5.bin / workbench / boot / czesc_1 / addmenu / addmenu.doc < prev    next >
Text File  |  1991-11-21  |  23KB  |  492 lines
  1.         AddMenu V1.56 (25th Sep 1991) by Nic Wilson
  2.         -------------------------------------------
  3.  
  4.         Written totally in Assembler
  5.         ----------------------------
  6.         using Hisoft Devpac Amiga 
  7.         -------------------------
  8.         on an Amiga A3000 25mhz
  9.         -----------------------
  10.  
  11.         Nic Wilson Software
  12.         138d South Street
  13.         Toowoomba Qld 4350
  14.         Australia  
  15.         Ph (076) 358384 Work or FAX
  16.            (076) 358539 After hours
  17.            
  18.         EMAIL {cbmvax|cbmehq}!cbmaus!wilson!nic@uunet.uu.net   
  19.  
  20.         This Version has been placed on Shareware for your enjoyment.
  21.         You may distribute it freely as long as this document and the 
  22.         program remains unmodified, and accompanies the program.  
  23.         You may modify the script files as examples as long as you 
  24.         FULLY test them before distribution.
  25.         
  26.         **************************************************************
  27.         
  28.         THIS VERSION IS ONLY A TASTE OF WHAT IT TO COME.  VERSION 2.00
  29.         IS NEARING COMPLETION AND HAS MUCH MORE POWER.  IT ALLOWS ICON
  30.         ITEMS ON SCREEN THAT CAN BE COMPLETELY CHANGED EACH TIME A NEW
  31.         SCRIPT IS LAUNCHED.  THIS GIVES IT MUCH MORE POWER THAT OTHER
  32.         PROGRAMS AROUND LIKE ADDMENU.  ADDMENU V2.00 WILL BE A 
  33.         COMMERCIAL PROGRAM BUT THE ASKING PRICE IS VERY REASONLBLE
  34.         AT $20.00 AND THIS ALSO GIVES YOU FREE UPDATES AND THERE ARE
  35.         OTHER UTILITIES ON THE DISK!!
  36.         
  37.         SEND FOR YOUR VERSION TODAY AND YOU WILL BE FIRST IN LINE
  38.         WHEN THE VERSION IS COMPLETE.  IT SHOULD BE READY BY THE
  39.         TIME YOU READ THIS.
  40.         
  41.         **************************************************************
  42.  
  43.  
  44.         FUNCTION
  45.         --------
  46.         Add an infinite number of Menu Items to the Workbench Tools 
  47.         Menu in Kickstart V2.0 using script files.  Updating is 
  48.         possible from the menus, from CLI or from Workbench using
  49.         different script files.  Temporary menu items can also be 
  50.         added that stay in the menu strip after updating to the new script,
  51.         and can also be converted to permanent and saved to your script
  52.         file automatically.
  53.  
  54.         REQUIREMENTS
  55.         ------------
  56.         Any Amiga running V2.0 of Kickstart and Workbench including
  57.         the A3000. Tested to versions 37.175 Kickstart and Workbench 37.66.
  58.  
  59.         HISTORY (Recent first)
  60.         ----------------------
  61.         
  62.         V1.56   Changed all the functions in the update window so they 
  63.                 return to the update window when their job is complete.
  64.                 This I thought was better then exiting the update window.
  65.                 Checked the program thouroughly with enforcer. 
  66.                 
  67.         V1.55   Added a new -s switch and completely changed the update
  68.                 window, to add the ability to save temporary menu items
  69.                 as permanent to the current script.  See -s option.
  70.                 
  71.                 Added a 'MAKE NEW SCRIPT' gadget to the update window.  See
  72.                 'MAKING A NEW SCRIPT FILE AUTOMATICALLY' for more info.
  73.                 
  74.                 Removed the string gadget in the update window and
  75.                 replaced it with a gadget that opens the asl.library file
  76.                 requester.  It defaults to S: where I expect most users
  77.                 would keep their script files, and it defaults to matching
  78.                 files with the pattern add#?.
  79.                 
  80.                 Added a 'Delete item from current script' function.  See
  81.                 'DELETING AN ITEM FROM THE CURRENT SCRIPT' for more info.
  82.                 
  83.                 Added a 'Reposition' function. This allows any items within
  84.                 the current script to be repositioned in any order.  See
  85.                 'REPOSITIONING ITEMS WITHIN THE CURRENT SCRIPT' for more info.
  86.                 
  87.                 Fixed a bug that must have been in for a while.  AddMenu would
  88.                 not launch with a script other than the default one.  This is
  89.                 now fixed.
  90.                 
  91.                 AddMenu can now be launched without any script files at
  92.                 all and be configured completely by the update window and
  93.                 dumping icons over its icon.
  94.                 
  95.                 AddMenu now hangs around a while if Workbench is busy on
  96.                 launch, and retries a few times before exiting.        
  97.                 
  98.         V1.54   Removed ability to run from Workbench because of severe
  99.                 problems in DOS being able to find things.  Run it from the
  100.                 user-startup and it is much better.                
  101.                         
  102.         V1.53   Changed launch code so the program can be called before 
  103.                 Workbench is available.  This allows the program to be called
  104.                 from the user-startup instead of the startup-sequence.  The
  105.                 program will detach itself and then hang around and wait
  106.                 until workbench is available before installing.  Also changed
  107.                 it so it can be launched from Workbench and gave it a commodity
  108.                 icon.  You can drag this into the WBSTARTUP drawer to launch
  109.                 it if you prefer.  If you do it this way the default script
  110.                 MUST be s:addmenu.script as WB parameters are not supported
  111.                 yet.
  112.          
  113.         V1.52   Very sorry but the new about function didn't work in hi-res.
  114.                 I only use interlace and I negelected to test other resolution
  115.                 modes.  It is now fixed.      
  116.          
  117.         V1.51   Added an 'About' menu automatically, this allows for easy
  118.                 identification of version number, author and info on its
  119.                 free distribution permission.  The 'About' menu will always
  120.                 be at the top of any function you have added in your script.
  121.          
  122.         V1.50   Fixed bug.  When updating to new script, old script memory 
  123.                 buffers were not being freed.   
  124.                 Added ability for each menu item to have more than one 
  125.                 executable(See 'COMMAND STRINGS' or 'EXAMPLE SCRIPT' BELOW).
  126.         
  127.         V1.41   Stopped illegal devices, drawers or non-executables
  128.                 being added to the menu strip.  These will cause
  129.                 workbench screen to flash.
  130.                 Added switch for temporary menus, so you do not have
  131.                 to have the icon around if you do not use them.
  132.                 Added the ability to remove the temporary menus alone.  
  133.         V1.42   Fixed bug.  If Temporary menus were removed, they would
  134.                 magically reappear when a script was changed.
  135.           
  136.         V1.40   New temporary menus via workbench icon added
  137.                 and ability to update or remove from this icon.
  138.         V1.31   Optimised and fixed error msg for illegal use
  139.                 under kickstart V1.3. 
  140.                 Fully checked with 'Enforcer' for bugs.
  141.         
  142.         V1.3    Added ability to change scripts on update.
  143.         
  144.         V1.2    Added quit and update options.
  145.         
  146.         V1.1    Added ability to use different script name/path.
  147.         
  148.         V1.0    Original release.
  149.         
  150.         IMPORTANT
  151.          ---------
  152.          DO NOT USE RUN OR RUNBACK, ADDMENU WILL RETURN THE CLI
  153.          TO YOU AND ALLOW IT TO CLOSE WHEN YOU GIVE AN ENDCLI.
  154.  
  155.          ADDMENU WORKS IN RATHER A SPECIAL WAY, IN ORDER TO ALLOW THE 
  156.          CLI WINDOW TO CLOSE AFTER LAUNCH IT RELAUNCHES ITSELF AGAIN 
  157.          WITH SPECIAL CODE, THIS IS DONE TO OVERCOME ALL THE NORMAL PROBLEMS 
  158.          ASSOCIATED WITH THIS.
  159.          YOU WILL NOTICE THAT SOME PROGRAMS LOSE THE PATH, STACK,
  160.          CURRENT DIRECTORY ETC. THIS IS ESPECIALLY TRUE OF PROGRAMS
  161.          WRITTEN IN C.  ADDMENU DOES NOT SUFFER FROM ANY OF THESE
  162.          PROBLEMS.  POPCLI TYPE PROGRAMS SUFFER BADLY FROM THIS, MY
  163.          AUTOCLI USES THIS SAME CODE AND SUFFERS NO PROBLEM.  IT IS
  164.          PUBLIC DOMAIN SO SEND S.S.A.E. AND DISK FOR THE LATEST VERSION.  
  165.          
  166. USAGE
  167. *****
  168.          AddMenu [script] [switch]  
  169.  
  170.          Standard redirection of output is supported. 
  171.          EG. Addmenu >nil: [script]  [switch] 
  172.         
  173. [switches]
  174.  
  175.   -s     AddMenu must already be running for this switch to be used.
  176.          is used to inform the running version that you wish to convert
  177.          any current temporary menu items in the current menu strip to
  178.          permanent and save them to the current script.  This allows you
  179.          to add items to each script file without having to manually
  180.          edit the script yourself.  This can also be done from the update
  181.          window accessed from AddMenu's special icon.
  182.  
  183.   -q     AddMenu must already be running for this switch to be used.
  184.          This switch allows the currently running AddMenu to be removed. 
  185.          If AddMenu is not found running an error message will result.
  186.          If this switch is used then it must be the only parameter.
  187.          To remove from workbench see 'To Remove Addmenu Completely'
  188.          below. 
  189.          
  190.   -t     Do not use temporary menus and do not place the icon on the
  191.          Workbench screen.       
  192.  
  193. [script] 
  194.          This is an optional parameter, and can be used when AddMenu is 
  195.          first launched or when updating.  By default it reads a script  
  196.          created by you, called 'addmenu.script'.  This file is expected 
  197.          to be in the S: directory , but if you wish to supply a
  198.          different path and name you can use the script parameter.  If 
  199.          this parameter is used you must supply the path to the file and 
  200.          its name.  There is an example file that accompanies this file 
  201.          to show you how to create it.  Below is an explanation of the 
  202.          script file.
  203.          
  204.          EG. AddMenu DH0:s/addmenu.myscript  
  205.              
  206.              or
  207.  
  208.              AddMenu s:addmenu.myscript
  209.          
  210. FROM Workbench
  211. --------------
  212.          This ability has been removed.
  213.  
  214. TEMPORARY MENU ITEMS
  215. ********************
  216.  
  217.          This function will default to on unless the -t switch was 
  218.          used at launch. AddMenu will place a special icon on the 
  219.          workbench window.  If a program is dragged and dumped over 
  220.          this icon, that program will appear at the bottom of the 
  221.          menu strip.  The program itself will not move at all and 
  222.          doing this is quite safe. These temporary menus will survive 
  223.          an update that changes to a different script.  They will 
  224.          continue to appear on the bottom of whatever script you 
  225.          update with. Once added they can be removed without removing 
  226.          AddMenu completely by double clicking on the special icon and
  227.          selecting the 'Remove Temporary Menu Items' gadget from the 
  228.          window.   If any illegal device or non-executable file is 
  229.          dumped over the icon the screen will flash and a beep sound 
  230.          will be heard, and it will not be added to the menu.
  231.          These temporary menu items can be converted to permanent and
  232.          saved to the current script by choosing the 'Save Temporary...'
  233.          gadget from the update window or by launching AddMenu again 
  234.          with the -s option.
  235.         
  236. ADDMENU's SPECIAL ICON
  237. **********************
  238.          
  239.          This icon does not behave like a normal icon, it is a special
  240.          icon that allows manipulation of AddMenu from the workbench.
  241.          Double clicking the icon will open a window with some gadgets.  
  242.          These gadgets allow AddMenu to be removed, temporary menus 
  243.          removed, updating a script or to cancel the operation etc.  They 
  244.          are all explained in the relative sections below.  This icon 
  245.          has not been given any specific position on the workbench window.  
  246.          Workbench will choose the best position for the icon, it can 
  247.          of course be dragged to any place you wish.  
  248.          
  249. CANCELLING THE WINDOW
  250. *********************
  251.          If you double clicked the special icon, the window opened, and
  252.          you changed your mind and wish to exit without changes.  Click
  253.          the 'CANCEL' gadget or the CLOSE gadget on the window.  This will
  254.          abort the operation and AddMenu will be unchanged. 
  255.  
  256. SAVING TEMPORARY MENU ITEMS TO THE CURRENT SCRIPT FILE
  257. ******************************************************
  258.  
  259. From CLI
  260. -------- Launch AddMenu again with the -s switch.  This will tell AddMenu
  261.          to convert the current temporary menu items to permanent and
  262.          save them to the current script file.  After this is done the
  263.          menus will be updated to reflect the temporaries as permanent.
  264.          This save option can save one or more temporary menu items
  265.          in one go.  You could also place 'AddMenu -s' into each script
  266.          file you use so it can be chosen from each menu, instead of the
  267.          CLI or update window.
  268.                          
  269. From Workbench
  270. --------------
  271.          Double click the special AddMenu icon that appeared on the 
  272.          workbench window when AddMenu was launched.  A window will
  273.          open.  Click the 'Save Temporary Menu Items to Current Script'
  274.          gadget.  If no temporary menus are found then this gadget will
  275.          be ghosted.
  276.                  
  277. TO REMOVE THE TEMPORARY MENUS
  278. *****************************
  279. From CLI
  280. --------        
  281.          Not possible.
  282.  
  283. From Workbench only
  284. -------------------
  285.          Double click the special icon that appeared on the Workbench
  286.          window when AddMenu was launched.  Click the 'Remove Temporary..'
  287.          Gadget.  All temporary menus will be removed.  They cannot be 
  288.          removed individually unless you convert them to permanent with
  289.          the 'Save Temp..' gadget and then the 'Delete Item..' to delete
  290.          specific ones.
  291.          If there are no temporary menus then the gadgets will be ghosted.
  292.  
  293. DELETING AN ITEM FROM THE CURRENT SCRIPT
  294. ****************************************
  295.  
  296. From CLI
  297. -------- The only way from CLI is to edit the script manually with an 
  298.          editor.
  299.  
  300. From Workbench
  301. --------------
  302.          Double click on the AddMenu icon and a window will open.  Click
  303.          on the 'Delete item from current script' gadget and another window
  304.          will open, this window will show all the items in the current 
  305.          script.  Each item is a toggle select gadget.  Choose one or
  306.          more entries to delete and when finished click the 'DELETE' gadget
  307.          and they are gone.  You may abort this function with the 'CANCEL'
  308.          gadget.
  309.  
  310. REPOSITIONING ITEMS WITHIN THE CURRENT SCRIPT
  311. *********************************************
  312.  
  313. From CLI
  314. -------- The only way from CLI is to edit the script manually with an 
  315.          editor.
  316.  
  317. From Workbench
  318. --------------
  319.          Double click on the AddMenu icon and a window will open.  Click
  320.          on the 'Reposition an Entry in Current Script' gadget and another 
  321.          window will open, this window will show all the items in the 
  322.          current script.  Each item is a toggle select gadget.  Choose two 
  323.          entries to swap place and they will swap.  Keep doing this until
  324.          all entries are in the position you desire them to be. When 
  325.          finished click the 'SAVE' gadget and your script file and the menu
  326.          strip will be updated to reflect these changes.  You may abort 
  327.          this function with the 'CANCEL' gadget.
  328.  
  329. UPDATING ADDMENU ONCE RUNNING
  330. *****************************
  331. From CLI
  332. --------         
  333.          If AddMenu is already installed when launched again, then it will
  334.          send a message to the running version to update itself,  If no
  335.          script is supplied then it will update from the default file.
  336.          A different script can be supplied as the update, and because this
  337.          update can be called from inside an AddMenu script, this allows 
  338.          you to change the entire menu, by calling a menu function.  
  339.          This allows for an infinite number of available menu functions.  
  340.          If a different script is supplied to the current one then it will 
  341.          be totally replaced in favour of the new script.  This new script
  342.          could of course have an option to return to the original or any 
  343.          number of other scripts.
  344.         
  345. From Workbench 
  346. --------------
  347.          Double click the special AddMenu icon that appeared on the 
  348.          workbench window when AddMenu was launched.  A window will
  349.          open.  Click the 'Change Tools Menu to different Script' gadget,
  350.          and a file requester will appear.  This file requester has a
  351.          pattern matching string gadget that will default to showing
  352.          all files that begin with 'add'.  I suggest that you call your
  353.          scripts addmenu.????? to take advantage of this, otherwise you
  354.          may click in the 'Pattern' gadget and change the display pattern.
  355.          Select your new script file, then the  menus will be updated if 
  356.          your new script was valid.  
  357.  
  358. TO REMOVE ADDMENU COMPLETELY
  359. ****************************
  360. From CLI
  361. --------
  362.          Launch AddMenu again with the -q switch. (SEE Usage Above)
  363.          This could also be done by placing an entry in your script
  364.          file so quitting could be done from the menus.
  365.  
  366. From Workbench  
  367. --------------
  368.          Double click the special icon that appeared on the Workbench
  369.          window when AddMenu was launched.  Click the 'Quit Addmenu'
  370.          Gadget.  AddMenu will be completely removed.
  371.  
  372. THE SCRIPT FILE
  373. ***************
  374.          The maximum number of items allowed in each menu script
  375.          is 63.  This is not a limitation of AddMenu, but a limitation
  376.          that Workbench has placed for the tools menu.  I do not
  377.          recommend using that many anyway, as they would be too
  378.          cluttered.  Use less per menu and make more scripts.
  379.          
  380. MAKING A NEW SCRIPT FILE AUTOMATICALLY
  381. **************************************
  382.          AddMenu can make a new script file for you automatically if
  383.          you wish.  To do this select 'MAKE NEW SCRIPT...' from the menu
  384.          and a file requester will open and prompt you for a new file
  385.          name for the script.  The S: directory will be the default
  386.          directory that the file requester will open in and the default
  387.          pattern matching will be add#?,  you may change this if
  388.          desired. Type a new file name or select an old one to overwrite 
  389.          and click on the LOAD gadget.  This new empty file will be 
  390.          created on the disk, and the menus will be removed, with only 
  391.          the 'ABOUT ADDMENU' and MAKE NEW SCRIPT...' items available.  
  392.          Drag programs you wish to place in this new script and dump 
  393.          them over the AddMenu Icon.  If the program you want to place 
  394.          in there does not have an icon, then select the 'All Files' 
  395.          sub-item from the 'Show' item of the Window menu of the workbench
  396.          window.  This will give all files and drawers a fake icon in the 
  397.          current window,  keep doing this until you get to your file.  
  398.          After you have placed all required files in the new menu, 
  399.          double-click on the AddMenu icon and select 'Save Temporary Menu 
  400.          Items to Current Script'.  The new script will be updated and 
  401.          will now be available.
  402.           
  403. MAKING A NEW SCRIPT FILE MANUALLY
  404. *********************************
  405.          The script file is a group of commands you would like in the
  406.          menu along with the text you want in the actual menu. 
  407.          The format of this script is important for the program to read 
  408.          it correctly.  If the number of menu items in a single script
  409.          overflows the screen height,  the menu strips will be made
  410.          wider and the items split into columns.  The maximum number
  411.          of menus items in a single script is 63, but due to a bug
  412.          in workbench.library this is not checked for, any extra menus
  413.          over this amount will be clipped, athough I dont forsee anyone
  414.          placing this many in a single script.  The structure of the
  415.          script file is as follows.
  416.  
  417. TEXT STRINGS
  418. ++++++++++++
  419.          The text strings are actually placed in the menu, and each one
  420.          must be before its command string.  The Text string MUST START 
  421.          and END with a plus (+) sign.
  422.  
  423. COMMAND STRINGS
  424. ***************
  425.          The command strings are the strings that are sent to DOS when
  426.          a menu item is selected.  Each one MUST come directly after
  427.          its text string and START and END with an asterisk (*).  There
  428.          are now any number of commands allowed per text string,  
  429.          DO NOT USE THE 'RUN' COMMAND WITHIN A COMMAND STRING,  'RUN'
  430.          WILL BE ADDED TO THE FRONT OF YOUR STRING AUTOMATICALLY.
  431.  
  432. END OF FILE MARKER (IMPORTANT!!)
  433. ################################
  434.  
  435.          The script file MUST END with a hash (#) sign on the beginning
  436.          of a new line.
  437.  
  438. COMMENTS
  439. ;;;;;;;;
  440.          Comments are allowed in the script file but must follow certain
  441.          guidelines.  They are allowed on a line of their own or beside
  442.          a text string or command string. They must be outside the command
  443.          or text string characters.  The best way to ensure this is to
  444.          leave at least one space before the beginning of the comment after 
  445.          the rightmost plus (+) or asterisk (*) of each comment or text
  446.          string.  They MUST NOT use the plus (+) sign, the asterisk (*) 
  447.          or the hash (#) sign within the comment, as these three 
  448.          characters are used to specify the beginning and end of command,
  449.          texts strings or end of file.  Comment lines are completely 
  450.          optional, you do not have to have any at all.
  451.  
  452. EXAMPLE OF A VALID SCRIPT 
  453. -------------------------
  454. ;this is a valid comment
  455. this is a valid comment
  456.     this is still a valid comment
  457. +NEWSHELL+                      ;Text for the menu surrounded in plus signs
  458. *c:newshell*                    ;commands surrounded in asterisk signs
  459.                                 comments are allowed between menu strings
  460. +NoVirus+                       this is still a valid comment
  461. *dh0:novirus*                   notice the path to the above command 
  462. +WordPerfect+
  463. *assign WP: dh0:wp*             an example of multiple commands
  464. *assign PRINT: dh0:wp*          with a menu entry.
  465. *assign SPELL.THES: dh0:wp*     
  466. *cd wp:*
  467. *wp*                            
  468. +XCOPY+                         to assign and run it
  469. *dh0:copiers/xcopy*             
  470. +Quit Addmenu+
  471. *addMenu -q*                    ;how to make AddMenu quit from the menus
  472.                                 
  473. +Another Menu+                  ;how to change menus from a menu 
  474. *addmenu s:different.script*    ;(updating AddMenu)
  475. #
  476.          Notice the 'end of file' marker (#) on the end of the script.
  477.          This is very important.
  478.          
  479.          
  480.          Please send comments, bug reports etc to the address at the 
  481.          top of this file.
  482.  
  483.          Nic Wilson
  484.  
  485.  
  486.  
  487.         
  488.  
  489.  
  490.  
  491.         
  492.